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Preface 



Audience 



Organization 



This manual explains how to use Sun SourceBrowser, a software tool 
for software developers. 

This manual is written for programmers who want to use 
SourceBrowser on Sun™ workstations running Sun C, FORTRAN, or 
Pascal. 

SourceBrowser can be used in either a window or command-line 
environment. If you want to use SourceBrowser in the window 
environment, you should be familiar with the SunViewl window 
environment. For information about Sun View™, see the SunViewl 
Beginner's Guide. 

This book includes five chapters and two appendices: 

Chapter 1 , “Introduction,” provides an overview of the capabilities of 
SourceBrowser. 

Chapter 2, “Using Sun SourceBrowser,” provides step-by-step 
instructions for using SourceBrowser in a window environment. 

Chapter 3, “Browsing Large Programs,” explains the procedures you 
will follow to use SourceBrowser in conjunction with large software 
projects. 

Chapter 4, “Window Command Reference,” provides a concise 
description of each SourceBrowser window command. 

Chapter 5, “Command-Line Reference,” describes how to use 
SourceBrowser in the command-line environment. 

Appendix A, “Browsing FORTRAN Programs,” provides a brief 
explanation of browsing FORTRAN programs. 
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Preface Continued 



Appendix B, “Browsing Pascal Programs,” provides a brief explanation^ 
of browsing Pascal programs. 

Typographical This book follows these typographical conventions: 

Conventions _ „ 

T imes Roman font, Italic face indicates: 

• A variable name 

• A command argument 
Courier font indicates: 

• A listing 

• A command name 

• A menu name 

• A program name 

Courier font, Bold face indicates what the user types. 
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1 . 1 Window and Command Line Environments 3 

1.2 How it Works 4 





Introduction 



Sun SourceBrowser is an interactive tool to aid programmers in the 
development and maintenance of software systems, particularly large 
ones. 

During the course of a programming project, new programmers often 
join the programming team to enhance, maintain, and port code. But 
before becoming productive team members, these individuals need to 
fully understand the code that they will modify. SourceBrowser is a 
powerful tool for helping programmers quickly grasp large programs. 
Specifically, SourceBrowser assists programmers by finding all 
occurrences of any symbol of their choice, including those found in 
header files. 

SourceBrowser uses a “what you see is what you browse” paradigm. In 
other words, the source code you manipulate is the same source code 
SourceBrowser uses in its searches. 

SourceBrowser is an extensible, open system that has been designed to 
be used with multiple languages. Currently, SourceBrowser can be used 
with Sun C, FORTRAN, and Pascal. 

1.1 Window and You can use SourceBrowser in either the SunViewl window 

Command Line environment or a command-line environment. The SunViewl 
Environments environment, in particular, is extremely easy to use. To issue a query, for 

example, you simply type the symbol you want SourceBrowser to find; 
then press Return. 

While the SourceBrowser window environment can be accessed only 
from Sun workstation, the command-line environment can be used from 
character terminals and from workstations emulating terminals. 
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Introduction 



1.2 How it Works You use SourceBrowser by issuing queries which instruct 

SourceBrowser to find all occurrences of the identifier, string constant, 
or search pattern that you have specified. You then view matches 
(occurrences of the symbol you requested SourceBrowser to find) with 
their surrounding source code. SourceBrowser maintains a list of all 
queries you have conducted during a SourceBrowser session. This 
makes it easy to issue a query, view the matches associated with that 
query, conduct another query and then return to your original query — 
all with a minimum number of commands. 

In addition to basic commands for issuing, adding, deleting, and moving 
between queries, SourceBrowser includes many powerful features. The 
Filter command, for example, lets you search for symbols based on 
the way in which they are used in a program, so you can issue very 
specific queries, such as “Show all occurrences of the variable age when 
agt is used as a structure field name.” To limit your search to specific 
items of certain classes of code, such as files or functions, you can use 
SourceBrowser’s Focus command. You also can edit code from 
within SourceBrowser. 

SourceBrowser maintain a high level of efficiency regardless of the size 
of the code you are browsing. That’s because, once SourceBrowser has 
built the database it uses to respond to queries, the size of the code you / 
are browsing has only minimal impact on SourceBrowser’ s speed. (See 
Section 3.8, “Performance Considerations,” for details.) 

SourceBrowser also includes several features specially designed for use 
with large programming projects. Chapter 3, “Browsing Large 
Programs,” describes those features. Note that, because SourceBrowser 
uses the selection service, it is integrated with other software 
development tools such as dbxtool. 
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Using Sun SourceBrowser 



This chapter gives you the information you need to use Sun 
SourceBrowser in a window environment. If you want to use 
SourceBrowser in the command-line environment, see Chapter 5, 
“Command-Line Reference.” 

All of the examples in this chapter are written in C. If you want to use 
SourceBrowser with FORTRAN programs, see Appendix A. If you want 
to use SourceBrowser with Pascal programs, see Appendix B. 

This chapter tells you how to 

• start SourceBrowser 

• change the current working directory 

• specify when SourceBrowser should build the index it uses to locate 
information in the SourceBrowser database 

• use SourceBrowser’s window environment 

• display the current match 

• view matches 

« remove matches 

• move between queries 

• remove queries 

• search for string constants 

• use wildcards in queries 

• use the Filter command to search for identifiers and string 
constants based on how they are used in a program 
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• use the Focus command to restrict a query to classes of code, such 
as files and libraries 

• edit code from SourceBrowser 

• use the property sheet to customize SourceBrowser 

• use SourceBrowser with dbxtool 

2.1 A Sample Throughout this chapter, the following sample program is used as the 

Program basis for all examples. 
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Figure 2-1 Sample Program 



texted it - sample.c, dir: /home/examples/browser 



B 


Scratch window 


B 


#ident "Source Browser Demo" 

♦ 


1 


#include <stdio.h> 


; 


#define SECOND ARY.DEMO times 




extern void hello(); 




extern void world(); 




void 




main(argc, argv) 




int argc; 

char *argv[]; 


f 




{ 




int times = 1; 








if (argc > 1) { 


P 


if (sscanf (argv[ 1] , "%d", &times) != 1) { 


|r 


times = 1; 




} 




} 




for (; times > 0; times — ) { 
hel lo(stdout) ; 


' 




world(stdout) ; 




} 




} 




static void 




heno(file) 




FILE ♦file; 




{ 


p' 


(void)fprintf (f i le, "Hello "); 


r 


} 


j 


static void 




world(file) 




FILE *file; 




{ 




(void)fprintf(file,. "world\n"); 


i 


} 



2.2 Compiling with SourceBrowser responds to queries by searching in a specialized 
the Source- database that contains pertinent information about the files you are 

Browser Option browsing. SourceBrowser’ s default is to build that database in the 

current working directory. If you want SourceBrowser to construct a 
database in a directory that is not the current working directory, see 
Chapter 3, “Browsing Large Programs.” 
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Before using SourceBrowser, you must recompile each of the source 
files you want to browse. 

To turn on SourceBrowser if you are using make: 

• Add -sb to CFLAGS in the makefile for C programs 

• Add -sb to FFLAGS in the makefile for FORTRAN 77 programs 

• Add -sb to PFLAGS in the makefile for Pascal programs 

The -sb option causes the compiler to add information to the 
SourceBrowser database. The information that is included depends on 
the particular compiler. In general, only identifiers and strings are 
included; that is, reserved words are not included. 

To turn on SourceBrowser if you are not using make: 

• add the -sb option to the compiler command line 

Figure 2-2 



Figure 2-3 

I venus% til -sb hello. £ -c 



Figure 2-4 Enabling Browsing from Pascal 

venus% pc -sb hello. p-c 



NOTES: To generate correct SourceBrowser information, you must issue a 
compile run that does not generate any warnings or error messages. 

Each source file compiled with the -sb option must have the same 
absolute path regardless of the machine from which it is referenced. If 
this is not the case, see Section 3-2, “Browsing From Multiple 
Machines.” 

You may find it useful to use SourceBrowser to browse declarations in 
Lint library specification files. To do that, compile the appropriate 
library specification file with the -sb option, as shown in Figure 2-5. 

Figure 2-5 Browsing Lint Library Specification Files 

venus% cc -c -sb /usr/lib/lint/llib-lc=. c -o /ten??/ junk, o 



Depending on which libraries you use, you may want to compile other 
files in /usr/lib/lint in the same fashion. 



Enabling Browsing from C 
venus% cc -sb hello. c -c 



Enabling Browsing from FORTRAN 77 
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Note that the ~.c portion of the command is necessary to inform the 
Compiler that you are compiling a C file, even though the filename 
doesn’t end with .c . The -o portion of the command is included to 
indicate that the result of the compilation is useless information. See 
Lint (1) for more about Lint files. 



2,3 Starting 

SourceBrowscr 



To start SourceBrowser: 

• type sbrowsers at the command prompt 



Figure 2-6 Starting SourceBrowser 



venus% sbrowser& 



SourceBrowser appears as a window similar to the following. 



Figure 2-7 SourceBrowser Window at Start-Up 







I Show KPreviousH Focus H_2uer^__J 


[ Erase 1[ Next ]{ Filter ] 


Scratch: ^ 











The content of the SourceBrowser window is explained in Section 2.8, 
“The SourceBrowser Window.” 



NOTE: To bypass additional introductory information and learn how to issue a 

query, see section 2.7, ''Issuing Queries.” 
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2.4 Changing the 

Current Working 
Directory 



SourceBrowser’ s default is to browse all source files described by the 
database in the current working directory. The current working directory 
is displayed in the frame header, the dark stripe that runs across the top 
of the SourceBrowser window. 



To change the current working directory from within SourceBrowser: 

1. Select the path to the desired directory. See the SunView 1 
Beginner's Guide for information about making selections. 

2. Position the pointer in the match subwindow (the middle 
subwindow) or the source subwindow (the bottom subwindow) and 
hold down the right mouse button to select Set Directory from 
the File pull-right menu of the Text Menu. 

Figure 2-8 Changing the Current Working Directory 



SunSourceBrowser — Current directory: /horne/exampies/textedit 



[ Shoui ][ Previous If Focus ]f Query 
[ Erase~lf Next ]f~F liter ] 
Scratch: 






I311.1 


Save Current File 


Query 


Edit 


Store as Hew File 


Next 


01 splaj 


Load File 


Previous 


Find 


Include Fi 1e 


Show 


Extras 




Erase ^ 

Filter 

Focus ^ 

Enable Ed1t*» 


n 


EB|»ty Docoaerit 

Finishing Up 
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2.5 Building the 
SourceBrowser 
Database Index 



When you issue a query, SourceBrowser searches in a specialized 
database containing data about your source code. When you issue your 
initial query following a compilation or recompilation, SourceBrowser 
builds an index for this databaseand then processes your query. 

You can, however, instruct SourceBrowser to conduct a query each time 
you run make. That way, the index will already be built when you issue 
your first query, so the query will be performed faster. 

To automatically rebuild the database index every time you run make, 
add the following lines to your makefile. 

.DONE; query 



query; 

-sbquery symbol_not_in_prog 

where symboljiotjn _prog is a symbol that does not appear in the code 
you are compiling. 

Another option is to instruct SourceBrowser to only update its database 
when you explicitly instruct it to do so. You do this by changing the 
Update Database for Each Query option in the property sheet 
to No. See Section 4.2, “The SourceBrowser Property Sheet,” for 
details. 

2.6 Querying Options As stated in the Introduction, a query is an instruction to SourceBrowser 

to find a specified symbol. To issue a query, you first need to determine 
the symbol you want SourceBrowser to search for. SourceBrowser can 
search for 

• identifiers 

• string constants 

• search patterns that contain wildcards 

SourceBrowser’ s default is to search for identifiers. See Section 2.14, 
“Searching for String Constants,” and Section 2.15, “Using Wildcards 
in Queries,” for instructions on searching for string constants and using 
wildcards in queries. 

2.7 Issuing Queries To issue a query to SourceBrowser, simply select the identifier you want 

SourceBrowser to search for and click left on the Query button. 

The identifier you select can appear in any open window. 
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The Initial Query 



Figure 2-9 



To issue the first query of a session (or to issue a query when no other 
query is displayed): 

1. Select the identifier you want to search for. The identifier can be: 

• an identifier you have typed in the Scratch field 

• an identifier in another window 



2. Click left on the Query button. 

For example, in Figure 2-9, the user instructed SourceBrowser to find all 
instances of file by typing /I/e in the Scratch field; selecting /I/e; then 
clicking left on the Query button. 

Issuing a Query 



SunSourceBrowser — Current directory: /horne/examples/broujser 



[ Erase 1 l Next ] f Filter ) 
Scratch: 

In function: hello 
File: sample. c 



^ Query: Cfile 
‘Match 1(4) 



Symbol: file 
Lines 28-41 



"sample. c”, line 30:[he11o] hello(file) 

"sample. c", line 31:[hello] FILE »file; 

"sample. c", line 37:[world] world(file) 

"sample. c", line 38:[world] FILE »file; 



static void 
|■►hello(file) 

■♦FILE *file; 

{ 

(void)fprintf(f i le, "Hello "); 

} 



static void 
|■♦uor1d(f i le) 
■♦FILE 



*fi le; 

(void)fprintf(f i le, "u»or1d\n"); 



See Section 2.8, “The SourceBrowser Window,” for a description of the 
content of each SourceBrowser subwindow. 
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Subsequent Queries 



The following is important additional information about issuing a query. 

• When using the Scratch field to issue a query, you can simply type 
the query in the Scratch field and press Return. 

• You can reduce the time it takes to respond to a query by half by not 
including the source code in the match sub window. You do this by 
setting the Match Window Contents option in the property 
sheet to Filename and Linenumber Only. See Section 4.2, 
“SourceBrowser IhDperty Sheet,” for details. See Section 3.9, 
"Performance Considerations,” for more about SourceBrowser 
performance. 

• To abort a query, press the Stop or LI function key. 

• If you receive a message starting “Request for xxx bytes of memory 
failed” you have run out of swap space. Use the mkf ile (8) 
command to create more swap space or the swapon (8) command 
to abort existing processes (windows) and free up existing 
swapspace. To determine which processes occupy significant swap 
space, use the ps uagx command and look in the SZ column. To 
determine how much swap space you have, use the pstat -s 
command. 

• If SourceBrowser displays messages indicating that it is having 
difficulty conducting a query (for example, if it says it is unable to 
find . bd— browser data— files), remove the .sb directory (that is, the 
directory containing the SourceBrowser database) and recompile 
everything with the -sb option. If you receive a message stating that 
the database is locked, you can either issue the -break_lock 
option or remove the .sb subdirectory and recompile. See Section 
5.4, “Command-Line Options,” for a description of the - 
break_lock option. 

• SourceBrowser uses standard C notation to display non-printing 
characters included in queries. 

Issuing subsequent queries is similar to issuing the initial query. The 

only difference is that you now have the option of choosing as your 

search symbol text that is displayed in the match subwindow or source 

sub window. 

To issue a subsequent query: 

1. Select the identifier you want to search for. The selected identifier 
can be an identifier that you have typed in the Scratch field or an 
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Figure 2-10 



identifier that appears in a SourceBrowser subwindow or in another 
window. 



2. Click left on the Query button. 

For example, in Figure 2-10, the user has instructed SourceBrowser to 
find all instances of void by selecting void in the source subwindow and 
then clicking left on the Query button. 

Issuing a Subsequent Query 



SunSourceBrowser — Current directory; /home/examples/browser 



[ Shoui HPreviousH Focus ] 1| 
[ Erase ][ Next ][ Filter 1 
Scratch: file 

File: sample. c 



Query: Cvold 
Match 1(8) 



Symbol: void 
Lines 1-30 



"sample. c", line 7:extern void helloO; 

"sample. c", line 8:extern void worldO; 

"sample. c", line 10:vo1d 
"sample. c", line 29:stat1c void 

"sample. c", line 33: [hello] (vold)fprintf (f 1 le, "Hello "); 



#ident "Source Browser Demo" 
#include <std1o.h> 

#def1ne SECONDARY.DEMO times 



’ extern 
■extern void 



helloO; 

uorldQ; 



■ void 

ma1n(argc, argv) 

int argc; 

char *argv[]; 



£ 



int 



times = 1; 



if (argc > 1) { 

if (sscanf(argv[l], "%d", &times) != 1) { 
times = 1; 

} 

} 

for (; times > 0; times — ) { 
hel lo(stdout); 
world(stdout); 

} 



static void 
'^T°^he1 1o(f i 1e) 
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2.8 The 

SourceBrowser 

Window 

Figure 2-11 

^ 

frame header 

► 

control subwindow 

> 

match subwindow 



> 

source subwindow 



The Frame Header 



The Control Subwindow 



The SourceBrowser window consists of a frame header and three 
subwindows: the control subwindow, the match subwindow, and the 
source subwindow. 



The SourceBrowser Window 



unSourceBrouiser — Current directory: /home/ examples/ browser 



[ Shew ~) [ Previous I [ Focus it Query 1 Query : vvoid 
I Erase if Next H Filter 1 ^ Match 1(8) 



Scratch: file. 



File: sample. c 



Symbol: void 
Lines 3-32 



"sample. c", line 7:extern void he11o(); 

"sample. c", line 8:extern void uiorld(); 

"sample. c“, line 10:void 
"sample. c", line 29:static void 

"sample. c", line 33: [hello] (void)fprintf (f i le, "Hello "); 



t] #include <stdio.h> 

#define SECONOARY.OEMO times 



helloO; 

worldO; 



extern 
extern void 



'void 

main(argc, argv) 

int arge; 

char *argv[]; 



{ 



int 



times = 1; 



} 



if (arge > 1) { 

if (sscanf (argv[l], "%d", &times) != 1) { 
times = 1; 

} 

} 

for (; times > 0; times — ) { 
hello(stdout); 
world(stdout); 

} 



H static void 
j^hello(file) 
-<>FILE 

{ 



•file; 



The SourceBrowser header is the stripe that runs across the top of the 
SourceBrowser window. When SourceBrowser is invoked, the header 
consists of SourceBrowser followed by the current working directory. 
The frame header also tells you whether filtering and/or focusing is 
turned on. 

The control subwindow contains the controls needed to manipulate 
SourceBrowser. Specifically, the buttons and underlying menus in the 
control sub window let you issue queries, move between matches 
(occurrences of the symbol specified by the query), move between 
queries, erase matches and queries, and narrow your search. 
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Figure 2-12 



Buttons and Menus 



Text Fields and Other Items 



The Control Subwindow 



[ Shoui ][Previoush Focus ]f Query ^ Query; vflle 
[ Erase ][ Next ][ Filter ] Match 1(6) 

Scratch: 

In function: hello Symbol: file 

File: sample. c Lines 30-41 



You use standard SunView conventions to manipulate buttons in the 
control subwindows. 

• To activate a button, position the pointer on the button and click the 
left mouse button 

• To display a menu under a button, position the pointer on the button 
and hold down the right mouse button 

Clicking left on a button is equivalent to choosing the first option in the 
menu behind the button. 

The control sub window contains one text field, called Scratch, that 
contains strings that you type. To issue a query you can simply type the 
identifier you want to search for in the Scratch field and press Return. 

After you have issued a query, the control subwindow also contains the 
following items: 

• In function specifies the function containing the current match (if 
applicable) 

• File specifies the file containing the current match 

• Query shows the current query 

• Match displays the total number of matches found during the current 
query and the number of the current match. For example, in Figure 
2-13, the current query has resulted in six matches, the first of which 
is the current match. The Match field also displays the number of 
secondary matches. See Section 2. 1 6, “Using the Filter Command to 
Narrow a Search,” for details. 

• Symbol displays the identifier or string constant for the current 
match 

• Lines displays the line numbers of the source code displayed in the 
source subwindow 
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The Match Subwindow 



The match subwindow is a subwindow that displays all matches found 
by the current query. When you issue a query, the first match 
SourceBrowser finds is defined as the current match. The current match 
is identified by a black arrow in the match subwindow. Matches 
containing declarations appear first in the match subwindow, followed 
by all other matches. 



Figure 2-13 The Match Subwindow 

"sample. c", line 7;extern void helloO; 

"sample. c", line 8: extern void uorldO; 

"sample. c", line 10:void 
"sample. c", line 29:static void 

"sample. c", line 33; [hel lo] (void)fprintf(f i le, "Hello 



Information about each match listed in the match subwindow includes 



• the name of the file in which the match appears, without the 
preceding path 



• the line number in the file on which the match appears 



• if applicable, the function in which the match appears 



• the line of code containing the match with preceding white space 
removed (optional) 



NOTE: 



The Source Subwindow 



SourceBrowser' s default is to display lines of code in the match 
subwindow and to truncate lines of code that don' t completely fit in the 
subwindow. If you want to eliminate source code from the match 
subwindow altogether, or wrap lines of code in the match subwindow, 
you can modify SourceBrowser' s property sheet. See Section 4.2, '‘The 
SourceBrowser Property Sheet," for details. 

The source subwindow displays the portion of source code that contains 
the current match. The source subwindow may also contain markers in 
the form of arrows that identify matches found during the current and 
other active queries. 
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Figure 2-14 The Source Subwindow 




black arrow 



gray arrow 



hollow arrow 



^ #1nclude <std1o 


.h> 


1 #define SEC0NDARY_DEM0 times 


extern BSHSI 


helloO; 


extern void 


uorldO; 


void 




^ main(argc, argv) 




argc; 

*argv[]; 


1 char 


I ^ 




9 


times = 1; 


^ if (argc > 1) { 


1 for (; 


if (sscanf(argv[l], &times) != 1) { 

times = 1; 

} 

times > 0; times — ) { 
hello(stdout); 
u)orld(stdout); 






1 ^ 




static void 
^^^“^heno(f i le) 




=^FILE 


♦file; 


I f 





• A solid black arrow indicates the current match 

• A gray arrow indicates a match other than the current match that has 
been found by the current query 

• A hollow arrow indicates a match found by a query other than the 
current query 

• A solid arrow with a line through it indicates a secondary match, that 
is, an identifier inside a macro definition. This marker only appears 
when you are using the Fi Iter command. See Section 16, “Using 
the Filter Command to Narrow a Search,” for details. 



NOTE: 



Displaying 

SourceBrowser Menus 



You can use the property sheet to instruct SourceBrowser not to display 
any of these markers in the source subwindow or to indent the markers. 
See Section 4.2, '‘The SourceBrowser Property Sheet,” for details. 

You can display SourceBrowser menus in either the match subwindow 
or the source subwindow by positioning the pointer in the subwindow in 
which you want the menu to appear and holding down the right mouse 
button. 
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Figure 2-15 



Scrolling in 

SourceBrowser Windows 



Displaying the SourceBrowser Menu 



SunSourceBrowser — Current directory: /home/exarnples/browser 



Shoul 



void 
Match’ 1(8) 



^ [Previous) [ Focus [ Query ] Query : 

[ Erase~l[ Next )[ Filter ] 

Scratch: fil^ 

File: sample. c 

"sample.c", nn?7?exterr^^™'™ToT^"" hello(); 
"sample. c“, line 8:extern void uiorld(); 

"sample.c", line 10:void 
"sample.c", line 29;static void 
J^samg1^^c%^Hne^3^[hel2£^^void)fgr1r^^ 
#include <stdio.h> 

#define SECONDARY.DEMO times 



Symbol: void 
Lines 3-32 



‘extern void 
extern void 



helloO; 

worldO; 



’ void 

main(argc, argv) 

int argc; 

char *argv[]; 



int 



times = 1; 



if (argc > 1) { 

if (sscanf(arg 



Text Menu ^ 
Query 







Next Match: This Query k 


Previous 

Show 

Erase 


■ iiiim— — I 


J 


ext Function I 

ext Hatch: Any Query | 


Filter — 

Focus < 

Enable Ed1t< 


s) '= 1) { 



for (; times > 8; times — ) { 
hello(stdout); 
uiorld(stdout); 

} 



■ static void 
;;l^hello(file) 
•»FILE 

{ 



•file; 



You can scroll through the match sub window and the source sub window 
using the scroll bars and can move and resize these subwindows by 
dragging their borders. For information about scrolling and resizing 
windows, see the SunView 1 Beginner’s Guide. 
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2.9 Redisplaying the 
Current Match 



Often, when using SourceBrowser, you’ll scroll through several 
screenfuls of source code in the source subwindow, so that the current 
match is no longer displayed. 

To redisplay the current match in the source subwindow: 

• Hold down the right mouse button and choose Current Match 
from the Show menu 



Figure 2-16 The Show Current Match Command 



[ ShotiJ 



[ Erase 



Scratch: 



Selected Match 



Current Match 



Versi on 



| [ Query ] Query: Ovoid 
|r I Match 1(8) 



File: sample. c 



Symbol: void 
Lines 3-32 



2.10 Viewing Matches 



SourceBrowser provides several ways to specify a different match as the 
current match. 



Using the Next Command 
to View Matches 



To make the next match in the match subwindow the current match and 
display the source code surrounding that match in the source 
sub window: 



• Click left on the Next button. This is equivalent to choosing Next 
Match: This Query from the Next menu. 



Figure 2-17 The Next Match: This Query Command 



i Shou) ][Previous][ Focus ][ Query ] Query: vvoid 

[ Erase i JBBSEBltf l Filter ] Match 1(8) 

Scratch: file ^ 

File: sample.c 



Symbol : void 
Lines 3-32 



% 
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You can also make the first match that occurs in the next function or file 
that contains a match the current match. When you do, SourceBrowser 
displays the source code surrounding that match in the source 
subwindow. 

To make the first match that occurs in the next function or file the 
current match: 

• Hold down the right mouse button and choose Next F i 1 e or 
Next Function from the Next menu 



Figure 2-18 The Next Function Command 




Using the Previous 
Command to View 
Matches 



To make the previous match in the match subwindow the current match 
and display the source code surrounding that match in the source 
subwindow: 



• Click left on the Previous button. This is equivalent to choosing 
Previous Match: This Query from the Previous menu. 

Figure 2-19 The Previous Match: This Query Command 
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You can also make the last match that occurs in the previous function or 
file that contains a match the current match. When you do, 
SourceBrowser displays the source code surrounding that match in the 
source subwindow. 

To make the last match that occurs in the previous function or file the 
current match: 

• Hold down the right mouse button and choose Previous File 
or Previous Function from the Previous menu 



Figure 2-20 The Previous Function Command 



[ Show ][ Previous 


Previous Match: This Query 


i 


void 




Previous File 


1 


) 






1 




Scratch: file 


Previous Match: Any Query 


1 








Symbol: void 


File: sample. c 




Lines 1-30 



Selecting a Different 
Current Match 



It’s often convenient to scroll through the match sub window until you 
find a match that you want to examine more closely. 



To make a match in the match subwindow the current match: 

1. Use the scroll bar in the match subwindow to scroll until the match 
you want to select is displayed. 

2. Select the match by clicking left anywhere on the line containing the 
match. 

3. Click left on the Show button. This is equivalent to choosing Show 
Selected Match from the Show menu. 
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Figure 2-21 



2,11 Erasing Matches 



The Show Selected Match Command 




For example, in Figure 2-21, the user selected the fourth line in the 
match sub window and then clicked left on the Show button. The black 
arrow moved to the selected match in the match subwindow and the 
surrounding source code was displayed in the source subwindow. 

When viewing matches, you may want to erase matches that are no 
longer of interest. 

To erase a match: 

1. Make the match you want to erase the current match. 

2. Hold down the right mouse button and choose This Match from 
the Erase menu. 

The number of matches shown by the Match item in the control 
subwindow is reduced by one. 
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Figure 2-22 The Erase This Match Command 



[ Shoui ~^fPrev1ous)[ Focus Query Query; 
f Erase | This Query j|lter ] Match 1(8) 



Scratch: 



Thi s Query ||1 ter 
All Queries 




File: sample.c 



Symbol: void 
Lines 3-32 



2.12 Moving Between During a SourceBrowser session, you often will issue several queries. 
Queries SourceBrowser maintains a list of these queries, called active queries, 

so you can easily move between them. 

When you move between queries, SourceBrowser retains the current 
match for each query. Thus, you can easily move between queries 
without losing your place in the code you are browsing. 

SourceBrowser provides multiple ways to move between queries. 

• You can choose a current query from the menu of active queries 

• You can cycle through the active queries 

• You can make the next match marked by a gray or hollow arrow the 
current match. (That is, you can make the next match appearing in 
the source code after the current match the current match even if the 
match was obtained by another query.) The query used to obtain that 
match then becomes the current query. 

• You can make the previous match marked by a gray or hollow arrow 
the current match (that is, you can make the previous match 
appearing in the source code before the current match the current 
match even if the match was obtained by another query.) The query 
used to obtain that match then becomes the current query. 

To choose a new current query from the menu of active queries: 

• Click right on the Query item and choose a query from the menu of 
active queries 



Figure 2-23 Displaying the Query Menu 



[ Show ][Previous][ Focus ][ Query 


^ Query: ■ 






f Erase ][ Next ][ Filter ) 


Match £ 


y/ void 1 




Scratch: file 






Symbol : void 


File: /usr/include/stdio.h 






Lines 48-73 



Selecting Queries from 
the Query Menu 
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Cycling Through Queries The cycle icon provides a quick way to view active queries. 

To cycle forward through the active queries: 

• Position the pointer on the cycle icon and click the left mouse button 
The Query item changes accordingly. 

Figure 2-24 The Cycle Icon 

[ Shou ~1[ Previous it Focus If" Query ] Query; 0^1 1e j 

[ Erase~lf Next ][ Filter ] Match 1(6) 

Scratch: file 
In function: hello 
File: sample. c 



Symbol: file 
Lines 9-38 



Using the Any Match 
Command 



To cycle backward through the active queries: 

• Position the pointer on the cycle icon, hold down the Shift key and 
click the left mouse button 

As you scroll through your source code, you may want to make the next 
match or previous match in the source code the current match. If the new 
current match was found by another query, that query becomes the 
current query and the Query item in the control subwindow changes 
accordingly. 

To make the next match the current match: 

• Hold down the right mouse button and choose Next Mat ch: Any 
Query from the Next menu 



Figure 2-25 The Next Match: Any Query Command 



[ Shoui ] [Previous] [ Focus ] [ Query ] Query : 

[ Erase )f Next 1(6) 



Scratch: file 
In function: hello 
File: sample. c 



Next Match: This Query 
Next File 
Next Function 



Next Match: Any Query 



Symbol: file 
Lines 9-38 
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To make the previous match the current match: 

• Hold down the right mouse button and choose P re vi ou s Match: 
Any Query from the Previous menu 



Figure 2-26 The Previous Match: Any Query Command 




2.13 Removing When a query is no longer of interest, you can remove it from the list of 

Queries active queries. 

To remove the current query from the list of active queries: 

• Click left on the Erase button. This is equivalent to choosing 
Erase This Query from the Erase menu. 



Figure 2-27 The Erase This Query Command 




2.14 Searching for SourceBrowser’s default is to search for identifiers. To instruct 

String Constants SourceBrowser to search for string constants: 

1. Select the string constant you want to search for. You can type the 
string constant in the Scratch field, enclosed in quotation marks, or 
you can select a string constant in the source subwindow or in 
another window. 

2, Click left on the Query button. 

For example, in Figure 2-28, the user instructed SourceBrowser to find 

all occurrences of “Hello”. 
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Figure 2-28 



2.15 Using Wildcards 
in Queries 



Searching for String Constants 



SunSourceBroujser — Current directory: /home/examples/browser 




When issuing a query, you can use wildcards to specify a search pattern. 
When using wildcards, SourceBrowser gives you two options: 

• shell-style patterns 

• regular expressions 

See sh(l) for information about shell-style pattern matching. 

A regular expression specifies a set of strings of characters. A member 
of this set of strings is said to be matched by the regular expression. In 
the following specification for regular expressions character means any 
character except NULL. 

1. Any character except a special character matches itself. Special 
characters are the regular expression delimiter plus ‘V’, 

“ .” and sometimes and “$”. 

2. A “. ” matches any character. 
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3. A*V followed by any character except a digit or “0” matches that 
character. 

4. A nonempty string s bracketed [s] (or ['^s]) matches any character 
in (or not in) s. In s, has no special meaning, and may only 
appear as the first letter. A substring a-b, with a and b in ascending 
ASCII order, stands for the inclusive range of ASCII characters. 

5. A regular expression of the form shown in items 1 through 4 
followed by matches a sequence of 0 or more matches of the 
regular expression. 

6. A regular expression, x, as in items 1 through 8, bracketed \(x) 
matches what x matches. 

7. A A” followed by a digit n matches a copy of the string that the 
bracketed regular expression beginning with the nth ‘X” matched. 

8. A regular expression of the form shown in items 1 through 8, x, 
followed by a regular expression of the form shown in item 7, y, 
matches a match for x followed by a match for y, with the x match 
being as long as possible while still permitting a y match. 

9. A regular expression of the form shown in items 1 through 8 
preceded by (or followed by “$”) is constrained to matches that 
begin at the left (or end at the right) end of a line. 

10. A regular expression of the form shown in items 1 through 9 picks 
out the longest among the leftmost matches in a line. 

SourceBrowser’ s default is shell-style expressions. If you want to use 
regular expressions, you need to change the SourceBrowser property 
sheet. See Section 4.2, “The SourceBrowser Property Sheet,” for details. 

NOTE: To limit the number of matches you receive when including wildcards in 

a query, it is often useful to use r/ie Filter command to search for 
items based on how they are used in a program. See Section 2.16, 
''Using the Filter Command to Narrow a Search,’* for details. 



Revision A of 16 March 1990 




Using Sun SourceBrowser 



31 



Figure 2-29 



To include wildcards in a query: 

1. Select the search pattern you want to search for. You can type the 
search pattern in the Scratch field or you can select a search pattern 
in another window. 

2. Click left on the Query button. Or, if you typed the pattern in the 
Scratch field, press Return. 

For example, in Figure 2-29, the user instructed SourceBrowser to find 
all instances of arg? 

Including Wildcards in a Query 



SunSourceBrowser — Current directory: /home/exarfiples/browser 



f Shoui ] [Previous]! Focus ] j 
[ Erase ][ Next ][ Filter ) 



if Query : G arg? 
^atch 1(6) 



Scratch; 

In function: main 
File: sample.c 



2 matches for source line 
Symbol : argc 
Lines 11-40 



•"sample.c", line ll:[main] ma1n(argc, argv) 

"sample.c", line ll:[ma1n] ma1n(argc, argv) 

"sample.c", line 12:[ma1n] Int argc; 

"sample.c", line 13:[ma1n] char *argv[]; 

"sample.c", line 17;[ma1n] If (argc > 1) { 



>ma1n(argc, argv) 

■♦int argc; 

■♦char *argv[3; 



{ 



Int 



times = 1; 



} 



•♦ If (argc > 1) { 

■♦if (sscanf(argv[l], "Xd", &times) != 1) { 
times = 1; 

} 

} 

for (; times > 0; times — ) { 
hello(stdout); 
uiorld(stdout); 

} 



'static void 
hel lo(f 1 le) 

FILE ‘file; 

{ 

■♦ (void)fprlntf(f 1 le, "Hello "); 

B^^static void 
u)orld(f lie) 



i 



FILE ‘file; 

(void)fprlntf(flle, "u)orld\n"); 



The Symbol item in the control subwindow displays the current 
identifier or string constant that matches the search pattern you have 
specified. 
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2.16 Using the 
Filter 
Command to 
Narrow a Search 



The Filter command lets you search for symbols based on how they 
are used in a program. 

You might, for example, want to limit your search to declarations of 
variables. 

If you issue a filtered query that is identical to another active query, 
SourceBrowser will ignore your request and redisplay the existing 
query. Thus, if you want to issue a filtered query that uses the same 
symbol as an existing query, you must first delete the existing query 
using the Erase Current Query command. 

You can have only one Filter setting for any query. 



NOTE: When you choose a different current query, the settings in the Filter 

panel change to reflect the settings you used when issuing that query. 
Thus, if you are moving between queries with different filters, you will 
avoid confusion by leaving the Filter panel in view. 



To use the Filter command to filter a query: 

1 . Click left on the F i 1 1 e r button. 

The Filter panel is displayed. The content of the Filter panel is 
determined by the language(s) of the code you are browsing. 

Figure 2-30 The Filter Panel 



SunSourceBrouiser Query Filter 



9 A11 Matches 
Q Declarations 
Q References 
Qcpp Floui Control 
Q Strings 
Q Pragmas 
Q Grep 
Qnake 



2. Click left on the menu item that describes the filter you want to use 
in your search. 

Depending on the item you choose, the Filter panel may expand to 
include additional menu items which you can use to further narrow your 
search. In Figure 2-31, for example, the user instructed SourceBrowser 
to search only for symbols that are used as declarations of variables. 
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Figure 2-31 



% 



Note that after you have specified a filter, the SourceBrowser frame 
header displays a message telling you that filtering is turned on. 

The Filter Panel after Specifying a Filter 



SunSourceBrouser Query Filter 



Active languages: sun_c 



Q A1 1 Matches 



Qa 11 Declarations BaII Variables 



8 Declarations B Variables 

Q References Q Functions 

Q cpp F1oui Control QTypedefs 
Q Strings QType Tags 

Q Pragmas Q Labels 

Q Grep Q Constants 

QMake Bcpp Symbols 



Q Static Variables 
Q Extern Variables 
OTopl evel Variables 
Q Local Variables 
Qpields 



3. If you want to close the Filter window, choose Done from the frame 
menu. 

4. Activate the SourceBrowser window and issue a query. 

In Figure 2-32, for example, the user instructed SourceBrowser to find 
all instances in which times is used as a variable declaration. 
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Figure 2-32 



>. 

secondary match 



A Special Case: Filtering 
Functions in Macro 
Definitions 



Issuing a Filtered Query 



unSourceBroujser — [Filter on] Current directory: /home/examples/browser' 



[ Shoui l[Previousir*'Focus 1 | 
[ Erase ][ Next ][ Filter ] 



[Query: C times [Filtered] 
Match 1(1+1) 



Scratch : 

In function: main 
File: sample. c 



Filtered query 
Symbol : times 
Lines 2-31 



"sample. c", line 15:[main] int times = 1; 
"sample. c", line 5:#define SECONDARY.DEMO times 



#include <stdio.h> 

►#define SECONDARY.DEMO times 



extern void 


helloO; 


extern void 


uiorldO; 


void 




main(argc, argv) 


int 


argc; 

»argv[]; 


char 


{ 




*♦ int 


times = 



} 

static 
ll^hel 1o(f 
-^1 





1 








■ 


QaII Matches 


QaII Declarations BaII Variables ji 


1 


8 Declarations 


B Variables 


©Static Variables 


i 


(qI References 


©Functions 


©Extern Variables 


1 


Qcpp Flow Control Qlypedefs 


©Toplevel Variables 


■ 


©Strings 


©Type Tags 


©Local Variables 


1 


Q Pragmas 


©Labels 


©Fields I 


1 


Q Grep 


© Constants 


1 


S 


©Make 


©cpp Symbols 





Notice that the current match is marked as a secondary match, that is, as 
a solid arrow with a white line through it. See the next section for an 
explanation of secondary matches. 

When SourceBrowser browses through source code, it is unable to 
determine how identifiers inside macro definitions are used. For 
example, in this code fragment from the sample program used in this 
chapter 

tdefine SECONDARY DEMO times 



int times = 1 

SourceBrowser does not know how times in the macro definition will be 
used. Consequently, when you use the Filter command to search for 
identifiers, as in Figure 2-32, SourceBrowser displays identifiers inside 
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Removing the Filter 



Figure 2-33 



2.17 Using the Focus 
Command to 
Narrow a Search 



macro definitions as secondary matches. When it is the current match, a 
secondary match is marked in the match subwindow as a solid arrow 
with a line through it Whenever SourceBrowser finds a secondary 
match, the total number of secondary matches is displayed in the Match 
item after the plus (+) sign. Thus in Figure 2-32, SourceBrowser has 
found one primary match and one secondary match. 

To disable the filter and instract SourceBrowser to find all occurrences 
of the symbol identified in your query: 

1. Activate the Filter panel. 

2. Select the A1 1 Mat che s item in the left column. 



Removing the Filter 



SunSourceBrouiser Query Filter Active languages: sun_c 



n ” 



Bah Matches BaH Matches 

Q Declarations m Variables 

Q References Functions 

Qcpp Flobi Control Q Types 
Q Strings QType Tags 

Q Pragnas Q Label s 

Q Grep O Constants 

QlMake Qcpp Symbols 



3. If you want to close the Filter window, choose Done from the frame 
menu. 

4. Activate the SourceBrowser window and issue a query. 



The Focus command lets you focus your search on instances of 
specific classes of code, such as programs, functions, or libraries. For 
example, you might want SourceBrowser to limit its search to specified 
functions. SourceBrowser then searches for occurrences of the symbol 
in any of the functions you have activated. 

Because SourceBrowser searches all source files described by the 
database in the current working directory, the Focus command is 
especially useful when you want to limit your query to selected files in 
a directory. 

You can use the Focus command to focus your query on more than one 
class of code. For example, you could conduct a query that was limited 
to certain files and libraries. 
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Once you use the Focus command to specify a focus, the focus remains 
in effect for all subsequent queries until you change the settings in each 
Focus panel. 

If you issue a focused query that is identical to another active query, 
SourceBrowser will ignore your request and redisplay the existing 
query. Thus, if you want to issue a focused query that is the same as an 
existing query, you must first delete the existing query using the E r a s e 
Current Query command. 

To issue a focused query: 

1 . Hold down the right mouse button and choose the class of code you 
want to focus on from the Focus menu. The content of the Focus 
menu changes depending on the language(s) of the source code you 
are browsing. 

Figure 2-34 The Focus Menu 




After a menu item is chosen, all of the available items for the selected 
class of code are displayed. 

Figure 2-35 The Focus Panel 
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Activate or deactivate the items you want to use in your search using 
commands found on the Activate and Deactivate menus. For 
example, in Figure 2-36, the user limited the search to identifiers found 
in the hello function by choosing Deactivate All Lines from 
the Deactivate menu, selecting hello; then choosing Activate 
Selected Lines from the Activate menu. Note that after you 
have specified a Focus item, the SourceBrowser frame header displays 
a message telling you that focusing is turned on. 

Figure 2-36 The Focus Panel with One Function Activated 




2. If you want to close the Focus window, choose Done from the frame 
menu. 

3. Activate the SourceBrowser window and issue a query. Note that 
SourceBrowser tells you when you are conducting a focused query. 
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Figure 2-37 



2.18 Editing Code 
from 

SourceBrowser 



Issuing a Focused Query 



SunSourceBrowser — [Focus on] Current directory: /home/exsmples/browser 



[ Shouj HPrevlousU Focus l l 
[ Erase If Next If Filter ] 
Scratch: tlme^ 

In function; hello 
File: sample. c 



[Query: Cflle [Focused] 
Match 1(3) 



g ""^^sampTe!7%^n^^T^fheno^TT^ 

"sample. c", line 33;[hello] (voli 





Focused query 
Symbol: file 
Lines 26-41 



♦file; 

(vold)fprlntf(flle, "Hello "); 



} 



static void 
J^hello(file) 

•♦FILE 

{ 

■♦ (void)fprlntf(file, "Hello "); 

} 

static void 
world(f ile) 

FILE ‘file; 



(void)fprintf(f i le, "uorldXn"); 



Focusing on Function — 3 entries, 1 active 




You can edit code without leaving SourceBrowser using SunView Text 
Edit’s editing commands. For information about these commands, see 
the SunView I Beginner's Guide. 

To edit code from SourceBrowser: 

1. Position the pointer in the source subwindow and hold down the 
right mouse button to display the SourceBrowser menu. 

• If your code is not part of the SCCS (or VCS for NSE™) file 

control system, choose the Enable Edit item 

• If the code is part of a file control system, choose Check Out; 

Then Enable from the Enable Edit pull-right menu in the 
SourceBrowser menu 
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Figure 2-38 



V 



NOTE: 



The Enable Edit Menu 



SunSourceBrowser — Current directory; /home/examples/browser 



i f Shooi l[Previous]f Focus Query ) Query; 
[ Erase ][ Next ]{ Filter ^ 



file 
Match 4(6) 



Scratch; fil^ 

In function: uiorld 
File: sample. c 



Symbol; file 
Lines 26-41 



^ "sample. c", line 37;[uor1d] uorld(file) 

"sample. c", line 38;[uorld] FILE »file; 

H "sample. c", line 33;[hello3 (void)fprintf(file, "Hello "); 
H "sample. c", line 48: [world] (void)fprintf (f i le, "worldXn"); 



T 



J^static void 
hello(file) 

■♦FILE *fi1e; 

■♦ (void)fprintf (f i le, "Hello 

} 



static void 
f*world(file) 
-♦FILE 



f i le; 

(void)fprintf (f i le, "worldX 



Text Menu ^ 

Query 

Next 

Previous 

Show 

Erase =» 

FI Iter 
Focus 








!jl Jill Check Out; Then Enable Edit | 



The pointer changes to a pencil. 

2. Edit the code. 

3. Disable editing. 

• To save your changes, choose Disable Edits from the 

SourceBrowser menu 

• If you don’t want to save your edits, choose Ignore Changes 

from the Disable Edits pull-right menu item in the 
SourceBrowser menu 

You cannot check files back in to SCCS or VCSfrom SourceBrowser. You 
must check them in manually. 
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2.19 Customizing The SourceBrowser property sheet lets you customize SourceBrowser 

SourceBrowser to suit your specific needs. 

To change SourceBrowser properties: 

1. Choose Props from the frame menu or press the L3 or Props key. 
Figure 2-39 The SourceBrowser Property Sheet 



SunSourceBrowser Properties 



Match Vindow: a Truncate Lines Q Vrap Lines 
Match Vindou) Contents: Opilename and Linenumber Only BaIso Show Source 

Selection Handling: 8 Do Not Change Selection QMove Selection To Show Match 

Arrows Displayed in Source Vindow: 

Arrow Positioning: Blndented Qin Margin 

Query Matching: 8 Use Case Q Ignore Case 
Wildcard Style: Bshell QRegular Expression 

Keep Database Index Updated: 8 Yes Q No 
Database Uodate Memorv Allocation: 02 Mbyte 

fApplyj [Reset] f Done ] 



2. Change the appropriate options. 

3. Click left on the Apply button. 

4. If you want to close the property sheet window, choose Done from 
the frame menu, or click the Done button. 



2.20 Using 

SourceBrowser 
with dbxtool 

When using SourceBrowser with dbxtool, set the Selection Handling 
option in the SourceBrowser property sheet to Move Selection to Show 
Match. That way, each time you move to another match, that match will 
automatically be selected. 

Begin by issuing a query that instructs SourceBrowser to find a variable 
that appears on the line at which you want to break. Then, use 
SourceBrowser commands to move between matches until the line of 
code at which you want to set a breakpoint is selected. 



For a complete description of each item in this panel, see Section 4.2, 
“The SourceBrowser Property Sheet..” 

You may find it convenient to use SourceBrowser in conjunction with 
dbxtool. Specifically, you can use SourceBrowser to search for a 
variable; then, make the appropriate occurrence of that variable a 
breakpoint in dbxtool. 
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Finally, click the stop at button in dbxtool. The breakpoint will be 
set at the selected line of source code in the SourceBrowser window. 
For more information about dbxtool, see dbxtool (1). 



Revision A of 16 March 1990 




42 



Using Sun SourceBrowser 



Revision A of 16 March 1990 





Browsing Large Programs 

3.1 Overview: The SourceBrowser Database 46 

3.2 Browsing From Multiple Machines 47 

3.3 Creating and Updating the Database 47 

3.4 More about .bd Files 49 

Compiling and Browser Data Files 49 

Linking and Browser Data Files 49 

Libraries and Browser Data Files 50 

3.5 Working with Multiple Directories ..50 

3.6 Installing a Symbolic Link 50 

3.7 Using .sbinit 51 

The import Command 52 

The export Command .53 

The split Command 56 

3 . 8 File Protection 58 

3.9 Performance Considerations 58 

Building the Index File 58 

Conducting a Query 58 




Browsing Large Programs 



Sun SourceBrowser responds to queries by searching in a specialized 
database that contains pertinent information about the files you are 
browsing. Knowledge of the layout of that database is especially 
important when you want to browse large programs whose source files 
are located in more than one directory. 

This chapter introduces you to the SourceBrowser database and the 
commands you used to manipulate it. Specifically, this chapter 
describes: 

• components of the SourceBrowser database 

• using SourceBrowser from multiple machines 

• creating and updating the SourceBrowser database 

• information about .bd (browser data) files 

• procedures for using symbolic links to organize databases 

• options for browsing databases contained in more than one directory 

• the .sbinit file, a textfile used by SourceBrowser to obtain 
information about the database structure and to improve 
SourceBrowser’ s performance when browsing large programs 

• information about database file protection 

• performance considerations 

NOTE: This chapter contains very general information that is likely to change 
in the future. Note too that the description of the structure of the .sb 
(SourceBrowser) subdirectory explained later in this chapter has been 
simplified. In reality, the structure of the subdirectory is more complex 
than the description included here. 
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3.1 Overview: The 
SourceBrowser 
Database 



The SourceBrowser database consists of two parts: 

• one file with an extension of .bd (browser data) for each source file 
for which you have generated SourceBrowser information. Browser 
data files are created by the compiler when you use the -sb option. 

• an index file created by SourceBrowser which SourceBrowser uses 
to locate information in the .bd files 



The .bd files and the index file are stored in the .sb (SourceBrowser) 
subdirectory. Unless you specify otherwise, the .sb subdirectory is 
created in the current working directory from which the compiler is 
executed. 

For example, in Figure 3- 1 , SourceBrowser databases are created in the 
.sb subdirectories in the sourcel and source2 directories. 

Figure 3-1 The SourceBrowser Database 




NOT E: T he asterisk (*) in each .bdfile is a place holder for a random string that 
is a hash value computed from the contents of the file. 

NOTE: The programatic interface to the SourceBrowser database is available 
to third party compiler writers. 

NOT E: T he SourceBrowser database is architecture independent. T hus, you can 

build a database on a Sun-3^ machine and then browse it on a Sun-4 
machine™. 



Revision A of 16 March 1990 




Browsing Large Programs 



47 



3.2 Browsing From 
Multiple 
Machines 



Each source file compiled with the -sb option must have the same 
absolute path regardless of the machine from which it is referenced. 
That’s because the .bd (browser data) files that are created when you run 
the compiler contain the absolute path for each source file. This 
information is used to display the source file when a query is issued. If 
the absolute path is not uniform across machines, SourceBrowser won’t 
be able to display the source files when it responds to a query. 

If SourceBrowser users are working on different machines, make sure 
that all source files are mounted at the same mount point. 



3.3 Creating and The first time you compile a source file with the -sb option, the 

Updating the compiler creates a .bd file for each file that you compiled. Then, prior to 

Database responding to your initial query following a compilation, 

SourceBrowser creates an index file which it uses to locate information 
in the .bd files. 

Each subsequent time that you compile a source file with the -sb 
option, new .bd files are created for source files that have been modified 
since the last compilation. When you issue your initial query following 
the compilation, SourceBrowser updates the index file before it 
responds to your query. 

Figure 3-2 illustrates the process. 
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Figure 3-2 Creating and Updating the Database 




Issue subsequent 
query 
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3.4 More about .bd 
Files 

Compiling and Browser 
Data Files 



This section describes the process of creating .bd files when you 
compile, link, or build a library. Note that this section presents very 
general information. 

When you compile with the -sb option, browser data (.bd) files are 
created for each source file. They are stored in the current working 
directory from which the compiler was executed. 

If it is the first time the source files have been compiled with the 
-sb option, the compiler creates a .sb subdirectory as well as a .bd file 
for each source file. For example, in Figure 3-3, the C compiler creates 
a c.c.*.bd file while the FORTRAN 77 compiler creates an f.f.*.bd file. 



If it is a recompile, .bd files are created for those files that have been 
changed since the last compile. 

NOTE: To generate correct .bd information, you must issue a compile run that 
does not generate any warnings or error messages. 

Linking and Browser Data When you link files that have been compiled with the -sb option, an 

Fties additional .bd file is created by the linker that lists the object files used 

to construct the program. For example, in Figure 3-3, the linker creates 
an a.out.*.bd file. 



Figure 3-3 Compiling with the -sb Option 



c . c 



f.f 




•matches 
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Libraries and Browser When you build a library with files that were compiled with the -sb 

Data Files option, a .bd file is created that lists the object files contained in the 

library. 



3.5 Working with 
Multiple 
Directories 



3.6 Installing a 
Symbolic Link 



Figure 3-4 



SourceBrowser’s default is to build its database in the current working 
directory, then search in that database when you issue a query. If you 
want to work with source files whose database information is stored in 
multiple directories, you have the following options: 

• You can create a common database that is used by all directories 
from which the compiler will be executed. To do this you must 
install a symbolic link to the common directory. See Section 3.6, 
“Installing a Symbolic Link,” for details. 

• You can browse multiple databases. To do this, you must include the 
import command in a text file called .sbinit. See Section 3-7, 
“Using .sbinit,” for details. 

• You can store SourceBrowser databases in directories other than the 
current working directory. To do this, you must include the 
export command in a text file called .sbinit. See Section 

3-7, “Using .sbinit,” for details. 

To browse databases stored in multiple directories, you can install a 
symbolic link to a common .sb directory from all directories in which 
the compiler will be executed. Figure 3-4 shows a conceptual view of 
installing a symbolic link to a common subdirectory. 

Installing a Symbolic Link 




Revision A of 16 March 1990 




Browsing Large Programs 



51 



Use one of the following options to create a symbolic link to a common 
.sb subdirectory: 

• Execute this command: 

In -s path/ . sb 

• Include the following code fragment in your makefile: 

.INIT: .sb 
. sb: 



-In -s path/ . sb 

Note that path can be relative or absolute. 

It often is useful to consolidate several databases into a single database. 
Suppose you wanted to move the databases in the .sb subdirectories in 
the source directories in Figure 3-1 to the project directory, as in Figure 
3-4. Figure 3-5 shows the steps you would follow to complete that 
process. 

Figure 3-5 Consolidating Databases 
venus% cd project 

venus% (cd sourcel ; tar cf - .sb) | tar xfB - 
venus% (cd source2 ; tar cf - .sb) | tar xfB - 
venus% rm -r£ sourcel /.sb source2/.sb 
venus% In -s ,./.sb sourcel/. sb 
venus% In -s ../.sb source2/.sb 
venus% rm -f .sb/Indez 



The second and third lines of code use the t ar command to move the .sb 
subdirectories in sourcel and source2 up one level. The fourth line of 
code removes the .sb subdirectories in sourcel and source2. The fifth 
and sixth lines of code create symbolic links to the .sb subdirectory in 
the project directory. The final line removes the Index file in the .sb 
subdirectory. Then, when you issue a query, a new Index file will be 
created in the .sb subdirectory in the project directory. 

3.7 Using .sbinit The .sbinit file is a text file used by SourceBrowser to obtain 

information about the database structure. The .sbinit file is limited to 
these commands: 

• The import command: reads databases in directories other than 
the current working directory used by SourceBrowser. 
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• The export command: writes databases associated with specified 
source files to directories other than the current working directory 
used by SourceBrowser and the compiler. When you include the 
export command in the .sbinit file, there is an implied import 
command. 

• The split command: speeds up SourceBrowser’ s performance by 
only updating relevant portions of the database used by 
SourceBrowser when the database is updated following a 
recompilation. 

These commands are explained in subsequent sections of this chapter. 

NOTE: SourceBrowser* s default is to look in the current working directory for 
the .sbinit file. If the .sbinit file is in another directory, or if you want to 
give the .sbinit file a different name, set the environment variable 
SUN _SOURCE_BROWSER JNlT FILE to the appropriate pathname. 
Setting SUN _SOURCE_BROWSER_INIT FILE also causes compilers to 
turn on the -sb option. 

The import Command The import command tells SourceBrowser which databases to read 

each time it performs a query. 

If you don’t include the import command or the export command 
in the .sbinit file, SourceBrowser only browses the database in the 
current working directory. (The export command is explained in the 
next section.) 

In contrast to installing a symbolic link, which creates a common 
database, the import command enables you to retain separate 
databases. For example, you may want to set up administrative 
boundaries so that programmers working on Project A cannot write into 
directories for Project B and vice versa. In that case. Project A and 
Project B will each need to maintain its own SourceBrowser database, 
both of which can then be read but not written by programmers working 
on the other project 

The import command has the form: 

import <path> 

where path is the path to the directory that contains the .sb subdirectory 
containing the database you want to import. 
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For example, in Figure 3-6, if your current working directory is /project/ 
source 1, and you want to instruct SourceBrowser to read the 
SourceBrowser database in source2, the import command in 
source I’s .sbinit file would be 

import /pro ject/source2 

or 

import ../source2 

Similarly, if your current working directory is /project /source2, and you 
want to instruct SourceBrowser to read the SourceBrowser database in 
sourcel, the import command in source2’s .sbinit file would be 

import /pro ject/sourcel 

or 

import ../sourcel 

When you recompile and issue a subsequent query, the databases for 
both sourcel and source2 are updated as appropriate if they can be 
written. 



Figure 3-6 Using the import Command 




The export Command You use the export command to cause the compiler to store specified 

browser data (.bd) files in a directory other than the current working 
directory.' This enables you to save disk space by placing .bd files 
associated with identical files, such as #include files from /usr/include, 
in a single SourceBrowser database while still retaining distinct 
databases for individual projects. If you don’t include a export 
command in the .sbinit file, the compiler writes all .bd files in the 
current working directory. 
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The export command has this form: 
export <preftx> into <path> 

Whenever the compiler processes a source file whose absolute path 
starts with prefix^ the resulting browser data (.bd) file will be stored in 
<path>/ . 

Note that the export command provides instruction for writing .bd 
files while the import command provides instructions for reading .bd 
and index files. 

In Figure 3-7, to place the .bd file and index file created for files from / 
usr/include in a .sb subdirectory in the sys subdirectory, the export 
command in the .sbinit file for source 1 would be 

export /usr/include into /project/sys 

If your configuration had included a source2 directory with a .sbinit file 
containing the same export command shown above, you would save 
disk space because, instead of creating two identical stdio.h.*.bd files, 
the compiler would create a single stdio.h.*.bd file in the sys 
subdirectory. 

Note that the .sbinit file contains an implied 
export / into . 

that instructs the compiler to put .sb files created by source files not 
explicitly mentioned by a export command in the current working 
directory. Thus, in Figure 3-7, the .bd files associated with a.c and b.c 
are placed in the .sb subdirectory in the source 1 directory. 

When you include the export command in the .sbinit file, there is an 
implied import command which causes SourceBrowser to read each 
database that you have instmcted the compiler to create. Thus, based on 
the configuration in Figure 3-7, SourceBrowser will search in the 
database in the sys subdirectory, as well as in the database in the source 1 
directory, each time you issue a query. 
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Figure 3-7 Using the export Command for Shared System Files 




venus% cd. /pro ject/sourcel 
venus% cc -sb -c a.c 



Figure 3-8 illustrates how to use the export command to store .bd 
files in a common subdirectory when the include file is located in a non- 
standard location. In this example, to place the .bd file and index file 
created for files from /project/include in a .sb subdirectory in the / 
project/include subdirectory, the export command in the .sbinit file 
for source 1 would be 

export /pro ject/include into /pro ject/include 

Here again, using the export command will save disk space when 
your program includes multiple references from many different 
directories to the same include file. 

Because the export command includes an implied import 
command, SourceBrowser will read the database in the include 
subdirectory as well as the database in the source 1 subdirectory each 
time you issue a query. 
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Figure 3-8 Using the export Command for Shared Project Include Files 





venus% cd /pro ject/sourcel 

venus% cc -sb -I /project /include -c a.c 



NOTE: If a .sbinit files includes multiple export commands, they are scanned 
in the same order that they are encountered in the .sbinit file. Thus, 
export commands should be arranged from most specific to least 
specific. 

The split Command The purpose of the split command is to improve performance when 

working with large numbers of programs. 

The split command, which must be included in the .sbinit file, has 
this form: 

split <size> 

where <size> is the size in bytes of the database index when the 
database will be split by SourceBrowser. 

The split command causes the SourceBrowser database to be split 
into a “new” and an “old” database whenever the database’s index file 
exceeds a specified number of bytes. Then, when you recompile, 
SourceBrowser places those .bd files that have changed since the last 
compilation into the new database, leaving the old database unchanged. 
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When you issue the initial query following compilation, a new index file 
is created in the new database, while the index file in the old database 
remains unchanged. This greatly speeds up SourceBrowser’s 
performance, since the time it takes to build the index file is proportional 
to the number of .bd files that require indexing. Consequently, it takes 
far less time to build the small index file in the new database than to 
build one large index file for the entire database. 

For example, in Figure 3-9, the database has exceeded the number of 
bytes specified by the split command in the .sbinit file in sourcel; 
consequently, the old database has moved down a subdirectory level and 
a new database is created in its place. In this example, the only source 
file that has been modified since the split is a.c; thus, the new database 
contains a.c.*.bd and an index file. 

Figure 3-9 Using the split Command 

project 



old 

database 



sourcel 




If the new database reaches the number of bytes specified by the size 
parameter of the split command, the old and new database files are 
merged, then split again. 
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3.8 File Protection 

3.9 Performance 
Considerations 

Building the Index File 



Conducting a Query 



UNIX® file protection modes control whether the SourceBrowser 
database will be updated when you recompile. If you have Read/Write 
access, the database will be updated. If you have Read Only access, the 
database will not be updated. 



This section describes those factors that determine the speed with which 
SourceBrowser builds the index file and conducts queries. Note that this 
is very general information. 

The time it takes SourceBrowser to build the index file the first time you 
query is proportional to the following: 

• The number of .bd files 

• The number of symbols in the .bd files 

• The size of the resulting index file 

The time it takes SourceBrowser to rebuild the index file following 
recompilation is proportional to the following: 

• the number of new .bd files 

• the sum of the number of symbols in all .bd files 

• the size of the index file 

The time required to conduct a query is determined by the number of .bd 
files that contain matches and the number of source files that contain 
matches. 

If the Match Window Contents option in the property sheet is set 
to Also Show Source, the speed of the query is also affected by the 
number of source files that contain matches. You can halve the time 
required to respond to a query by setting this option to F i 1 ename and 
Linenumber Only. 

The time required to conduct a query that includes wildcards is based on 
the time it takes to conduct a query without wildcards as well as the size 
of the index file. 
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Window Command Reference 



4.1 SourceBrowser 
Menu Commands 



NOTE: 



The Show Menu 



[ Show Selected Hatch 
Current Hatch 
Version 



This chapter provides reference information about Sun SourceBrowser 
window commands. Specifically, it includes 

• a description of each SourceBrowser menu command with its 
command line equivalent 

• a description of each option on the SourceBrowser property sheet, 
with its command-line equivalent 

SourceBrowser commands can be activated either by clicking the 
appropriate button in the control subwindow or choosing the appropriate 
menu item in the control subwindow, or by accessing the 
SourceBrowser menu from the match subwindow or the source 
subwindow. 

Clicking left on a button in the control subwindow is equivalent to 
choosing the first option in the menu behind the button. 

The only SourceBrowser-specific menu commands that are not 
accessible through menus in the control subwindow are the Enable 
Edi t and Disabl e Edi t commands. These commands must be 
activated by displaying the SourceBrowser menu in the source 
subwindow. See Section 2.18, ''Editing Code from SourceBrowser,” for 
details. 

The following sections describe each command as it appears in the 
control subwindow. 

Holding down the right mouse button when the pointer is positioned on 
the Show button activates a menu with the following items. 

Selected Match: (This is the default.) Makes the selected match in 
the match subwindow the current match and displays the appropriate 
line of code in the source subwindow. This command is useful when you 
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The Erase Menu 



[ Erase This Query 
This Hatch 
All Queries 



The Previous Menu 



[PreviousI Previous Natch: This Query 
Previous File 
Previous Function 
Previous Match: Any Query 



want to scroll through the match subwindow until you find a match that ^ 
you want to make the current match. 

Current Match: Displays the current match in the source 
subwindow. This command is useful when you have scrolled through 
the source subwindow and want to redisplay the current match in that 
subwindow. 

Version : Displays SourceBrowser’s current version number. This 
command is equivalent to the -version command line option. 

Holding down the right mouse button when the pointer is positioned on 
the Erase button activates a menu with the following items. 

This Query: (This is the default.) Erases the current query. Once a 
query is erased, it is removed from the Query menu. Using this 
command reclaims memory. 

This Mat ch: Erases the current match. This command is useful when 
you are reviewing matches and only want to retain those matches that 
are of interest to you. 

All Queries: Erases all active queries. Using this command 
reclaims memory. 

Holding down the right mouse button when the pointer is positioned on 
the Previous button activates a menu with the following items: 

Previous Match : This Query: (This is the default.) Makes the 
previous match found by the active query the current match and displays 
it in the match subwindow and the source subwindow. 

Previous File: For the current query, makes the last match that 
occurs in the previous file that contains a match the current match and 
displays that match in the match subwindow and the source subwindow. 

Previous Function: For the current query, makes the last match 
that occurs in the previous function that contains a match the current 
match and displays that match in the match subwindow and the source 
subwindow. 

Previous Match: Any Query: Makes the previous match in the 
source subwindow the current match. If the new current match was 
found by another query, that query becomes the active query and the 
Query item in the control subwindow changes accordingly. 
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Holding down the right mouse button when the pointer is positioned on 
the Next button activates a menu with the following items: 

Next Match : This Query: (This is the default.) Makes the next 
match found by the active query the current match and displays it in the 
match subwindow and the source subwindow. 

Next File: For the current query, makes the first match that occurs in 
the next file that contains a match the current match and displays that 
match in the match subwindow and the source subwindow. 

Next Funct i on: For the current query, makes the first match that 
occurs in the next function that contains a match the current match and 
displays that match in the match subwindow and the source subwindow. 

Next Match : Any Query: Makes the next match in the source 
subwindow the current match. If the new current match was found by 
another query, that query becomes the active query and the Query item 
in the control subwindow changes accordingly. 

Holding down the right mouse button when the pointer is positioned on 
the Focus button activates a menu with items representing classes of 
code. 

The content of this menu changes depending on the language(s) used to 
write the source files you are browsing. 

After you choose an item from the Focus menu, all of the available items 
from the class of code you have selected are displayed in a Focus 
window. Use the Activate and Deactivate menus described 
below to activate and deactivate the items you want to use in your 
focused query. Note that when you first open this window, all items are 
activated. 



Figure 4- 1 The Focus Window 
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The Activate Menu 




See Section 2.17, “Using the Focus Command to Narrow a Search,” for 
more about the Focus command. 

The Focus window contains two menus: Activate and 
Deactivate. 

The Activate menu in the Focus window is used to activate specific 
code items. The Activate menu contains these items: 

Activate Selected Lines (This is the default.) Activates 
selected items. 

Activate Not Selected Lines activates all items that are not 
selected. 

Activate All Lines activates all items. 



Activate According to Pattern activates items based on the 
search pattern you have selected. 

The Deactivate Menu xhe Deact ivate menu in the Focus window is used to deactivate 

specific code items. The Deactivate menu contains these items: 




Deactivate Selected Lines (This is the default.) Deactivates 
selected items. 

Deactivate Not Selected Lines deactivates all items that are 
not selected 



Command-Line Equivalent Deactivate All Lines deactivates all items. 

Deactivate According to Pattern deactivates items based 
on the search pattern you have selected. 

This item is equivalent to using the -in_* command-line option to 
specify a focusing option. To receive a list of command-line focusing 
options, use the -help_f ocus option. See 

-help_focus in Section 5.4, “Command-Line Options,” for details. 
The Filter Command Clicking left on the Filter button displays the Filter panel. 

You use the Filter panel to conduct a search based on how symbols are 
used in a program. 

The content of the Filter panel changes depending on the language(s) 
used to write the files you are browsing. See Section 2.16, “Using the 
Filter Command to Narrow Your Search” for more about the F i Iter 
command. 
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To receive a list of filtering options from the command line, use the 
-help_f ilter option followed by the language of the source code 
you are browsing. See -help_f ilter in Section 5.4, “Command- 
Line Options,” for details. 

Clicking left on the Query button causes SourceBrowser to search for 
the selected symbol. 

You also can issue a query by typing the symbol in the Scratch field and 
then pressing Return. 

Clicking left on the Update button causes SourceBrowser to update the 
Index file. 

This button only appears if you have set the Keep Database 
Index Updated item in the SourceBrowser property sheet to no. If 
that is the case, you need to click the Update button whenever you 
want SourceBrowser to update the database. 

If you have set this item to yes, SourceBrowser updates the database, 
then processes your query when you issue your initial query following a 
compilation or recompilation. 

To display the SourceBrowser property sheet, choose Props from the 
frame menu or press the F3 or Props button. 

The SourceBrowser Property Sheet 



SunSourceBrowser Properties 



Match Vlndou: Hlruncate Lines Qvrap Lines 
Match Vindou) Contents: 13 Filename and Linenumber Only OH A Iso Show Source 

Selection Handling: BDo Not Change Selection 0Move Selection To Show Match 

Arrows Displayed in Source Window: 

Arrow Positioning: H Indented Qin Margin 

Query Matching: BUse Case (3 Ignore Case 
Wildcard Style: B Shell 3 Regular Expression 

Keep Database Index Updated: BVes 3 No 
Database Update Memory Allocation: C2 Mbyte 

[Apply] [ Reset j [Done] 



To hide the Property sheet, but retain the current settings, click Done. 

The items in the SourceBrowser property sheet are explained in the 
following sections. 



Command-Line Equivalent 



The Query Button 



[ Quei"y J 

The update Button 

[ Update ] 



4.2 SourceBrowser 
Property Sheet 

Figure 4-2 
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Match Window 
Match Window Contents 

Command-Line Equivalent 
Selection Handling 

NOTE: 

Arrows Displayed in 
Source Window 



Arrows Positioning 
Query Matching 

Command-Line Equivalent 



Truncate Lines truncates lines of code in the match subwindow. 
This is the default Wrap Lines wraps lines of code so that the 
complete line of source code is displayed. 

Filename and Line Number Only does not display the source 
code line in the match subwindow. Choosing this option causes a fifty 
percent improvement in performance when conducting queries. Also 
Show Source displays the source code line, along with the filename 
and line number, in the match subwindow. This is the default. 

See -no_source in Section 5.4, “Command-Line Options,” for 
information about the equivalent command-line option. 

Do Not Change Select ion does not move the selection bar to the 
current match in the source subwindow when a new current match is 
displayed. This is the default. Move Selection to Show Match 
selects the current match in the source subwindow when a new current 
match is displayed. 

This item does not take effect until you choose a different match as the 
current match. 

Determines which arrows are displayed in the source subwindow. 

• A black arrow indicates the current match 

• A gray arrow indicates a match other than the current match that has 
been found by the current query 

• A hollow arrow indicates a match found by a query other than the 
current query 

If you click the black arrow box, only black arrows will be displayed. If 
you click the gray arrow box, gray and black arrows will be displayed. 
If you click the hollow arrow box, all three kinds of arrows will be 
displayed. 

Indented indents arrows so that they line up with the first line of 
source code. This is the default. In margin places arrows in the left 
margin. 

Ignore Case causes SourceBrowser not to look at case when 
searching for symbols in the source code that match the query symbol. 
Use Case causes SourceBrowser to only make a match when the case 
of the symbol matches the case of the symbol in the source code. This is 
the default. 

See -no_case in Section 5.4, “Command-Line Options,” for 
information about the equivalent command-line option. 
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Wildcard Style 



Command-Line Equivalent 



Keep Database Index 
Updated 



Command-Line Equivalent 

Database Update Memory 
Allocation 



Command-Line Equivalent 



Shell informs SourceBrowser that you are using shell-style patterns 
when using wildcards in a query. This is the default. Regular 
Expressions informs SourceBrowser that you are using regular 
expressions when issuing a query that includes wildcards. 

See Section 2.15, “Using Wildcards in Queries,” for more about using 
wildcards in a query and about pattern matching using regular 
expressions. See sh(l) for information about shell-style pattern 
matching. 

See -reg_expr in Section 5.4, “Command-Line Options,” for 
information about the equivalent command-line option. 

Yes instructs SourceBrowser to update the index file before the initial 
query after a compilation is processed. This is the default. No instructs 
SourceBrowser not to automatically update the database. When you 
choose No, a new button. Update, is added to the control subwindow. 
You click left on this button each time you want to update the index file. 

See -no_update in Section 5.4, “Command-Line Options,” for 
information about the equivalent command-line option. 

This is a cycle item that tells SourceBrowser the approximate amount of 
memory that should be allocated before SourceBrowser uses temporary 
files when building the index file. 

See -max_memory in Section 5.4, “Command-Line Options,” for 
information about the equivalent command-line option. 
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Command-Line Reference 



The Sun SourceBrowser command-line environment is a conventional 
command-style interface that can be accessed from Sun workstations, as 
well as from character terminals and from workstations emulating 
terminals. 

This chapter explains how to issue a query from the command line and 
how to use SourceBrowser’s command-line options. 

5.1 Sample Program Throughout this chapter, the following sample program is used as the 

basis for all examples. This program is written in C. For information 
about using SourceBrowser with Sun FORTRAN programs, see 
Appendix A. For information about using SourceBrowser with Sun 
Pascal programs, see Appendix B. 
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5.2 Viewing 

Command-Line 

Options 



To obtain a list of the SourceBrowser’s command-line options, 
• type sbquery when the Unix shell prompt is displayed 




Figure 5-2 SourceBrowser Command-Line Options 



venusQbreeze { 5 } % 


sbquery 


sbquery [options] 


A 

(0 

o 

(A 

V 


All lines 


! that contain symbols are. displayed. 


General options 




-break lock 


Break the database lock. 


-no update 


Do not update the index file. 


-files only 


Only show the names of the files with matches. 


-help_f ocus 


Show focusing options. 


-help_f liter <language> Show filter options for <language>. 


-max memory <size> Amount of memory to use when building index. 


-no_case 


Ignore case information during lookup 


-no__source 


Do not show source line containing match. 


-o <file> 


Send output to <file>. 


-reg_expr 


Use grep-style regular expressions. 


-symbols_only 


Display list of symbols that match search pattern. 


-version 


Display the current version number. 



5.3 Issuing a Query To issue a query from the command line: 

• type sbquery, followed by any command-line options and their 
arguments, followed by the symbol you want to search for 

For example, in Figure 5-3 the user instructed SourceBrowser to ignore 
all case information and display all the appropriate matches, that is, all 
lines of code in the current working directory that contain the symbol 
times. 

SourceBrowser then displays a listing that includes the file in which the 
symbol appears, the line number on which the symbol appears, the 
function, if any, in which the symbol appears, and the line of source 
code containing the symbol. 

Figure 5-3 Issuing a Query from the Command Line 

venus8breeze{ 6} % sbquery -no_case times 
"sample. c", line 15; [main] int times = 1; 

"sample. c", line 5:#define SECONDARY DEMO times 

"sample. c", line 18: [main] if (sscanf (argv[l] ,:"%d",:&times) != 1) { 

"sample. c"/ line 19; [main] times = 1; 

"sample. c", line 23: [main] for (; times > 0; times — ) { 

"sample. c", line 23: [main] for {; times > 0; times — ) { 
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NOTE: 

NOTE: 

5.4 Command-Line 
Options 

-break__lock 

-no__update 

Menu Command Equivalent 
-files_only 



SourceBrowser* s default is to search for symbols in the SourceBrowser ^ 
database in the current working directory. If you want to browse a 
database stored in another directory, see Chapter 3, “Browsing Large 
Programs.*' 

SourceBrowser can search for identifiers, string constants, and search 
patterns that contain wildcards. SourceBrowser* s default is to search 
for identifiers. For instructions on searching for a string constant, see 
Section 2.14, “Searching for String Constants.** For instructions on 
using wildcards in a query, see Section 2.15, “Using Wildcards in 
Queries.** 

The following is a description of each SourceBrowser command-line 
option. 

Breaks the lock on a locked database. If the update of the index file is 
aborted for some reason (e.g. a power failure), SourceBrowser will 
display a message telling you that the database is locked the next time 
you issue a query. When you use the -break_lock option to break 
the lock, your database may be in an inconsistent state. To ensure 
consistency, remove the .sb subdirectory and recompile. 

Causes SourceBrowser not to rebuild the index file when you issue a 
query following compilation. If you do not include this option and issue 
a query following compilation or recompilation, SourceBrowser 
updates the database; then processes your query. 

For more information, see section 2.5, “Building the SourceBrowser 
Database.” 

This option is equivalent to setting the Keep Database Index 
Updated item in the property sheet to no. 

Lists the files in which the symbol you are searching for appears. When 
you use this command with back quotes, you can take SourceBrowser 
output and use it as ah argument to another command. For example, this 
command 

edit 'sbquery -files_only hello' 

reads into the editor all files containing the symbol hello. For 
information about using back quotes to redirect output to another 
command see sh(l) or csh(l). 
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Displays a list of the classes of code that you can focus on. You then can 
issue a focused query, that is, a query that is limited to specific classes 
of code such as specific programs or functions. Because SourceBrowser 
automatically searches through all files described by the database in the 
current working directory, the Focus option is especially useful when 
you want to limit your search to certain programs in a directory. 

Issuing the -help_f ocus option without any arguments displays a 
list of the classes of code that you can use to limit your search. 

Figure 5-4 Using -help_focus To Display Focusing Options 



venusGbreeze { 9 } % sbquery -help__f ocus 
-injprogram <Program> Focus query < 
-in_library <Library> Focus query ( 
-in_file <File> Focus query < 
-in_file <Macro> Focus query c 
-■in_file <Function> Focus cjuery < 
-in_^language <Language> Focus query c 



query on 
query on 
query on 
query on 
c[uery on 
query on 



Program units 
Library units 
File units 
Macro units 
Function units 
Language units 



To limit your search to a specified class of code, type sbquery 
followed by the class of code you want to focus on, followed by the 
specific unit of code you want to search in, followed by the symbol you 
want to search for. Note that you can include multiple classes of code in 
a query. 

Because SourceBrowser automatically searches through all files 
described by the database in the current working directory, the Focus 
option is especially useful when you want to limit your search to certain 
programs in a directory. 

In Figure 5-5, the user instructed SourceBrowser to find all instances in 
which times is used in function main. Notice that SourceBrowser 
displays one fewer match than in Figure 5-3, which was not a focused 
query. 



Figure 5-5 Using -helpjocus To Issue a Focused Query 



venus0breeze{ 10 } % sbquery -in__function main times 
"sample. c”, line 15; [main] int times = 1; 

"sample. c", line 18: [main] if (sscanf (argv [1] , "%d", %times) ! = 
"sample. c", line 19; [main] times = 1; 

"sample. c", line 23: [main] for (; times > 0; times — ) { 
"sample. c", line 23: [main] for (; times > 0; times — ) { 




Revision A of 16 March 1990 










76 



Command-Line Reference 



/ 

Menu rnminanH Equivalent ** equivalent to the Focus command in SourceBrowser’s 

window environment. 



help__filter Issuing this option without any arguments causes SourceBrowser to 

display a list of the languages for which filtering options are available. 
(You use filtering options to search for symbols based on how they are 
used in a program.) 

Figure 5-6 Using ’help Jilter To Display Supported Languages 



venusQbreeze{ll }% sbquery *-help__£il'ber 

The '-help^f liter' option must be given with one of the following arguments: 
-help_filter ansi_c 
-help_filter base 
^help__f liter cpp 
-help_filter executable 
-help^f liter extend 
-help_filter focus 
-help^^f liter library 
-help__f liter sun_c 
-help_filter sun_cpp * 

-help^filter sun_^f77 
-help_filter sun_pascal 



Issuing this option followed by a language supported by SourceBrowser 
causes SourceBrowser to display a list of filtering options for that 
language. Figure 5-7 shows a partial listing of these options for Sun C. 



Figure 5-7 Using -help Jilter To Display Filtering Options 



venus0breeze{12}% sbquery -help__filter sun__c | more 

— all_matches 

All mentions of the symbol 
-all_matches-all_matches 

All mentions of the symbol 
-all_matches -variables 

All uses as a variable 
-all_matches-variables-all_variables 
All uses as a variable 
-all__matches-variables-regular_variables 

All uses as a non-field variable 
-all_matches-variables-field_variables 
All uses as a field 

-all_matches -variables -field_variables-all_fields 
All uses as a field 

-all_mat ches -variables- field_variables -St ruct_fields 
All uses as a struct field 



Specifying the filter followed by the symbol you want to search for 
causes SourceBrowser to conduct a filtered query. 
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For example, in Figure 5-8 the user instructed SourceBrowser to find all 
instances in which times is used as a variable declaration. 



Figure 5-8 Issuing a Filtered Query 



venus@breeze{ 6} % sbquery -‘declaration-variables times 
" sample. c", line 15: [main] int times - 1; 

.. "sample. c", line 5:?#define SECONDARY DEMO times 



Menu Command Equivalent 
-max_memory <size> 

Menu Command Equivalent 
-nocase 

Menu Command Equivalent 

-no_source 

Menu Command Equivalent 



The filter can be shortened between the dashes as long as it still is a 
unique filter. For example, -declaration-variables could be shortened to 
-decl-var. 

Note that the question mark (?) that appears in the final line of output in 
Figure 5-8 represents a secondary match. Because SourceBrowser is 
unable to determine precisely how identifiers inside macro definitions 
are used in a program, SourceBrowser identifies all identifiers inside 
macro definitions as secondary matches. For more about secondary 
matches, see Section 2-16, Using the Filter Command to Narrow a 
Search. 

This option is equivalent to the Filter command in SourceBrowser’ s 
window environment. 

Tells SourceBrowser the approximate amount of memory, in 
Megabytes, that should be allocated before SourceBrowser uses 
temporary files when building the index file. 

This option is equivalent to specifying the Database Update 
Memory Allocation item in the property sheet. 

Instructs SourceBrowser not to look at case when searching for symbols 
in the source code that match the query symbol. If you do not use this 
option, SourceBrowser only makes a match when the case of the symbol 
matches the case of the symbol in the source code. 

This option is equivalent to setting the Query Matching item in the 
property sheet to Ignore Case. 

Causes SourceBrowser to display only the filename and line number 
associated with each match. If you do not include this option, 
SourceBrowser also displays the line of source code containing the 
match. 

This option is equivalent to setting the Match Window Contents 
option in the property sheet to Filename and Line Number 
Only. 
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-o <file> 
-reg__expr 



Menu Command Equivalent 
-symbolsonly 

-version 

Menu Command Equivalent 

5.5 Non-Standard 
Installation 
Procedure 



Sends SourceBrowser output to a file instead of to standard out. 

Indicates that you are using regular expressions when issuing a query 
that includes wildcards. If you do not include this option, 
SourceBrowser assumes you are using shell-style patterns. 

See Section 2.15, Using Wildcards in Queries, for more about using 
wildcards in queries and about regular expressions. See sh(l) for 
information about shell-style pattern matching. 

This option is equivalent to setting the Wildcard Style item in the 
property sheet to Regular Expressions . 

Displays a list of all symbols that match the pattern specified in your 
search pattern. This option is only useful when you use wildcards in a 
query. 

Displays SourceBrowser’ s current version number. 

This option is equivalent to choosing Vers ion from the Show menu, 



SourceBrowser relies on finding the file sun_source_browser.ex in a 
certain location. If you install in a non-standard way such that the file is 
not found where expected, the system returns an error message when 
you run a SourceBrowser. To correct the error, set the environment 
variable SUN_SOURCE_BROWSER_EX_FILE to the absolute pathname 
of sun_source_browser.ex. The variable must be set each time you rur 
SourceBrowser. 
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Browsing FORTRAN Programs 

This appendix explains those features of Sun SourceBrowser that are 
unique to browsing FORTRAN files. Specifically, this appendix 

• explains how to enable SourceBrowser from FORTRAN 

• shows how to browse a FORTRAN program from the window 
environment 

• shows how to browse a FORTRAN program from the command- line 

• describes how to set the case option so it is suitable for browsing 
FORTRAN programs in the window and command line 
environments 

A.l Startup To turn on SourceBrowser if you are using make, add -sb to FFLAGS 

in the makefile. 

To turn on SourceBrowser if you are not using make, add the -sb 
option to the FORTRAN compiler command line. 

Figure A- 1 Enabling Browsing from FORTRAN 
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A.2 Sample Program Throughout this appendix, the following sample FORTRAN program is 

used as the basis for the examples. 

Figure A-2 Sample FORTRAN Program 

I Scratch window 

— — . 1 — 

I program example 

integer argc 
integer times 
character*^© argv 

data times/ 1/ 

argc = iargc() 

if (argc .le. 0) goto 10 

call getarg(l, argv) 

read (unit=argv, fmt=*, err=99) times 

goto 10 

99 times = 1 

10 do 20 count = 1, times 

call he11o(6) 
call uor1d(6) 

20 continue 




B\ 



subroutine hello(ud) 
integer ud 

write (ud, ♦) ''Hello '' 
end 

subroutine world(ud) 
integer ud 

write (ud, *) ''world'' 
end 
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A.3 Browsing from 
the Window 
Environment 

Issuing a Query 



Figure A-3 



Chapter 2, Using Sun SourceBrowser, provides a complete description 
of the SourceBrowser window environment. This section provides two 
brief examples of browsing FORTRAN source code. 



You use the same procedure to query a FORTRAN program that you use 
to query a C program. For example, in Figure A-3, the user instructed 
SourceBrowser to find all instances of argv by typing argv in the 
Scratch field selecting argv, and then clicking left on the Query button. 

Issuing a Query 



SunSourceBroiuser — Current directory: /usr2/cta/f77 



[ Shoui KPrevioush Focus ] 



[ ErasG 1[ Next ][ Filter ) 



Query; O argv 

Match 1<3) 



Scratch: 

In function: example 
File: example. f 



Symbol : argv 
Lines 1-30 



^ "example. f‘, line 10: [example] call getarg(l, argv) 

"example. f", line ll:[example] read (unit=argv, fmt=*, err=99) times 




20 



program example 
integer argc 
integer times 
^character»40 argv 

data times/ 1/ 

argc = iargc() 
if (argc .le. 0) goto 10 
■♦call getarg(l, argv) 

"♦read (unit=argv, fmt=», err=99) times 
goto 10 
times = 1 

do 20 count = 1, times 
call hello(6) 
call world(6) 
continue 

end 

subroutine hello(ud) 
integer ud 

write (ud, *) ■'Hello ■’ 
end 

subroutine world(ud) 
integer ud 

write (ud, *) ''world^ 
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Issuing a Filtered Query 



Figure A-4 



SourceBrowser’s filtering options are determined by the language of 
the source code you are browsing. Figure A-4 shows an example of the 
Filter panel that is displayed when you query a FORTRAN program. In 
that example, the user instructed SourceBrowser to find all instances in 
which argc is used as a variable declaration. 



Issuing a Filtered Query 




SunSourceBrouJser — [Filter on] Current directory: /usr2/cb/f77 



Query 



[ Shou) )[PreviousH Focus ] 1 
[ Erase j[ Next ][ Filter t 



Scratch: 

In function: example 
File: example. f 



Query; argc [Filtered] 

>1atch 1(1) 

Returning to existing query 
Symbol : argc 
Lines 2-31 



■♦integer argc 
integer times 
character*40 argv 

data times/1/ 

argc = iargcO 

if (argc .le. 8) goto 10 

call getarg(l, argv) 

read (unit=arg'i», fmt=*, err=99) times 

goto 10 

99 times = 1 

10 do 20 count =1, times 

call hello(6) 



20 



SunSourceBrouiser Query Filter Active language 



QaII Matches 
B Declarations 
Q References 






Q Strings 
Q Grep 
QMake 



QaII Declarations 


Bah Variables 


B Variables 


0 FORTRAN Forma Is 


Q Programs 


0 Common Block Members 


Q Functions 


0 Pointer Variables 


Q Volatiles 


0Data Words 


QSave Items 


0 Fields 


Q Name list Items 




Qintrinsics 




Q Impl icits 




Q Equivalences 




Q Common Blocks 




Q Block Data Labels 




13 Type Tags 




(3 Labe Is 




3 Constants 




Qcpp Symbols 
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A.4 Using the 

Command-Line 

Environment 



Chapter 5, “Command-Line Reference,” contains a complete 
description of the SourceBrowser command-line environment. This 
section contains a brief example of browsing a FORTRAN program 
from the command line. 



To issue a query from the conmiand line: 

• type sbquery, followed by any command-line options and their 
arguments, followed by the symbol you want to search for 

For example, in Figure A-5 the user has instructed SourceBrowser to 
ignore all case information and display all the appropriate matches, that 
is, all lines of code in the current working directory that contain the 
symbol argv. 

SourceBrowser then displays a listing that includes the file in which the 
symbol appears, the line number on which the symbol appears, the 
function in which the symbol appears, and the line of source code 
containing the symbol. 

Figure A-5 Issuing a Query from the Command Line 

venusQbreeze { 10 } % sbquery -no__case argfv 
"example. f'r line 4: [example] character*40 argv 
"example. f", line 10: [example] call getargd argv) 

"example . f”, line 11: [example] read (unit^argv, fmt=*, err=99) times 



A.5 Turning Off Case When browsing FORTRAN programs, SourceBrowser should ignore 

case. There are two ways to set the case option: 

• If you are using SourceBrowser from the window environment, set 
the Query Matching option in the Property Sheet to Ignore 
Case. See Section 4.2, “SourceBrowser Property Sheet,” for more 
information. 

• If you are using SourceBrowser from the command line, include the 
-no_case option when issuing a query, as in Figure A-5. 
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Browsing Pascal Programs 



This appendix explains those features of Sun SourceBrowser that are 
unique to browsing Pascal files. Specifically, this appendix 

• explains how to enable SourceBrowser from Pascal 

• shows examples of using SourceBrowser’ s window environment to 
query a Pascal program 

• shows an example of using SourceBrowser’s command-line 
environment to query a Pascal program 

B.l Startup To turn on SourceBrowser if you are using make, add -sb to PFLAGS 

in the makefile. 

To turn on SourceBrowser if you are not using make, add the -sb 
option to the Pascal compiler command line. 

Figure B-1 Enabling Browsing from Pascal 

venus% pc -sb hello. p -c 
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Browsing Pascal Programs 



B.2 Sample Program Throughout this appendix, the following sample Pascal program is used 

as the basis for all examples. 

Figure B-2 Sample Pascal Program 



textedit - example. p, dir: /home/examples/browser/pascal 



B 


Scratch uindou 


B 


program example( input, output); 




type 


1 


argv_type = packed array[l. . 100] of char; 




var 




argc_cnt: integer; 


} 


count: integer; 




argv_string: argv_type; 




format: argv_type; 


h - 

s. 

r 


procedure sscanf(ptr, format: univ_ptr; var i: integer); external; 




procedure hello(var fd: text); 


I- 


begin 




write(fd, ‘'Hello 


f 


end; 


h 


procedure world(var fd: text); 




begin 




writeln(fd, ‘'world''); 




end; 




begin 




if argc > 1 then begin 




argv(l, argv_string); 




format := ''%d^; 




sscanf (addr(argv_string), addr (format), argc_cnt); 




end else begin 




argc_cnt := 1; 




end; 




for count := 1 to argc_cnt do begin 




hel lo(output); 


. 


world(output); 


' 


end; 


i 


end. 
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B.3 Browsing from 
the Window 
Environment 

Issuing a Query 



Figure B-3 



Chapter 2, “Using Sun SourceBrowser,” provides a complete 
description of the SourceBrowser window environment. This section 
provides two brief examples of browsing Pascal source code. 



You use the same procedure to query a Pascal program that you use to 
query a C program. For example, in Figure B-3, the user instructed 
SourceBrowser to find all instances of argv by typing argv in the 
Scratch field, selecting argv, and then clicking left on the Query 
button. 

Issuing a Query 



SunSourceBrouiser — Current directory: /usr2/cb/pc 
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Issuing a Filtered Query 



Figure B-4 



B.4 Issuing a Query 
from the 
Command Line 



SourceBrowser’s filtering options are determined by the language of the 
source code you are browsing. Figure B-3 shows an example of a Filter 
panel that is displayed when you query a Pascal program. In that 
example, the user instructed SourceBrowser to find all instances in 
which is used as a variable declaration. 



Issuing a Filtered Query 





[ Shoul ] {Previousi [ Focus 1 Query : 0 ar gc_cnt 


[Filtered] 


[ Erase ][ Next U Filter ] ^Match 1(1) 




Scratch: 


Filtered query 


In function: example 


Symbol : argc_cnt 


File: example. p 


Lines 1-30 




program 8xample(1nput, output); 
type 

argv.type = packed array[l. . 100] of char; 
var 

*^argc_cnt: integer; 
count: integer; 
argv_string: argv_type; 
format: argv_type; 

procedure sscanf(ptr, format: univ_ptr; var i: integer); external; 

procedure hello(var fd: text); 
begin 







f I n 





begin 




QaII Matches 



QaII Declarations BaII Variables 



B Declarations BVariables 

B References B Programs 

Bcpp Floui Control B Routines 
B Strings B Types 

BCrep B Labe Is 

B Make B Constants 

B cpp Symbols 



B Public Variables 
B Local Variables 
Bpields 

B Private Variables 



To issue a query from the command line: 

• type sbquery, followed by any command-line options and their 
arguments, followed by the symbol you want to search for 

For example, in Figure B-5, the user instructed SourceBrowser to 
display all the appropriate matches, that is, all lines of code in the current 
working directory that contain the symbol argv. 
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SourceBrowser then displays a listing that includes the file in which the 
symbol appears, the line number on which the symbol appears, the 
function, if any, in which the symbol appears, and the line of source 
code containing the symbol. 

Figure B-5 Issuing a Query from the Command Line 

venus(3breeze{10}% sbquery argv 

’’example. p", line 24: [example] arcrv(l, argv_string) ; 
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